Contents

1 General 1 1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Initialisation . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 Runtime Tailoring . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.4.1 Logging Levels . . . . . . . . . . . . . . . . . . . . . . 2 1.4.2 Logging structures . . . . . . . . . . . . . . . . . . . . 2 1.4.3 Logging macros . . . . . . . . . . . . . . . . . . . . . . 3

1.5 Code location . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.5.1 Library code . . . . . . . . . . . . . . . . . . . . . . . 5 1.5.2 Core Programs . . . . . . . . . . . . . . . . . . . . . . 6 1.5.3 Other directories . . . . . . . . . . . . . . . . . . . . . 6

2 Message Submission 7 2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2 The io Interface . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.2.1 Major Structures . . . . . . . . . . . . . . . . . . . . . 8 2.2.2 Reply value structure . . . . . . . . . . . . . . . . . . 22 2.2.3 Procedure Calls . . . . . . . . . . . . . . . . . . . . . . 22 2.2.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2.3 The RFC 822 interface . . . . . . . . . . . . . . . . . . . . . . 28 2.3.1 Initialisation . . . . . . . . . . . . . . . . . . . . . . . 28 2.3.2 Addresses and Headers . . . . . . . . . . . . . . . . . . 29 2.3.3 Text Submission . . . . . . . . . . . . . . . . . . . . . 30 2.3.4 Termination . . . . . . . . . . . . . . . . . . . . . . . . 30

2.4 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3 Channels 32 3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 3.2 The Queue Interface . . . . . . . . . . . . . . . . . . . . . . . 32

3.2.1 Major Structures . . . . . . . . . . . . . . . . . . . . . 32 3.2.2 Basic Access . . . . . . . . . . . . . . . . . . . . . . . 34 3.2.3 Delivery Notifications . . . . . . . . . . . . . . . . . . 39 3.2.4 Verification and Trust . . . . . . . . . . . . . . . . . . 41

3.3 Example usage . . . . . . . . . . . . . . . . . . . . . . . . . . 43 3.3.1 Outbound Channels . . . . . . . . . . . . . . . . . . . 43 3.3.2 Local Pickup . . . . . . . . . . . . . . . . . . . . . . . 45 3.3.3 TWA channel . . . . . . . . . . . . . . . . . . . . . . . 45 3.3.4 Delivery Reports . . . . . . . . . . . . . . . . . . . . . 45

3.4 Formatters and Converters . . . . . . . . . . . . . . . . . . . 45 3.4.1 Simple converters . . . . . . . . . . . . . . . . . . . . . 45 3.4.2 Complex Filters . . . . . . . . . . . . . . . . . . . . . 46 3.4.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 1

General

1.1 Overview

There are certain approaches taken by PP processes. These are described here, to facilitate emulation by new processes. These are not strict guidelines, but following existing practises will usually be easier and make upgrading the software less painful.

1.2 Initialisation

All PP programs generally start by calling one or more initialisation routines. This may vary depending on what the channel needs to know. This initialisation does various things amongst which are

• Reading global parameters from the tailor file.

• Initialising the logging packages.

• Handling of signals.

The normal method of initialising a process is to call the following routine very early on (usually one of the first things).

     sys_init (name)
     char *name;

This routine does most of the initialisation required. The argument is usually the value of argv[0] which is used in the logging initialisation to record the name of this program.

1.3 Runtime Tailoring

The runtime tailoring for PP is complex, as there are many parameters that can affect the operation of the system. The main things tailored are pathnames to locate commonly used programs; file names and directories; or the more complex tailoring to define such things as channels and tables. See Volume 1 for the full detail.

LLOG NONE Not logged
LLOG FATAL Fatal errors
LLOG EXCEPTIONS Exceptional events
LLOG NOTICE General information
LLOG PDUS Printing of Protocol Data Units
LLOG TRACE Program Tracing
LLOG DEBUG Full debugging
LLOG ALL All Values

Table 1.1: Logging Levels

To add new items to be tailored, it is necessary to add some code to the parsing routines. For simple additions, it is necessary only to modify the tables and the switch statement in the file pp/Lib/tai/tai sys.c. More complex tailoring is best done my creating a separate procedure, possible in a new file. Such additional tailoring should not be undertaken lightly as it will make the new version of PP incompatable with existing and new versions.

1.4 Logging

All logging works through a standard package. This package includes features to limit the log files and to notify administrators of errors. The logging has some structure too it and the following are the general rules used when programming PP.

1.4.1 Logging Levels

The logging package takes a bit mask of values to log. This is compared with the current setting of the logging level and then certain values are logged. The levels available are shown in Table 1.1. The values LLOG_NONE and LLOG_ALL are special – the first is no logging at all, the latter sets all bits in the bitmask.

1.4.2 Logging structures

There are three log structures used in PP. The structures themselves are defined in the include file isode/logger.h. These structures are of type LLog * and are the following.

Structure  Usage
log norm Normal logging
log oper Critical Operator message
log stat Statistical and Authorisation